feat(contextual-help): S2 migration #3909

cdransf · 2025-06-06T23:08:02Z

Description

CSS-819

S2 migration for contextual help

This migrates the contextual help component to the latest Spectrum 2 designs. Custom properties have been remapped and added per the design specification.

Typographic and color tokens have been updated per design specifications.

All existing popover positioning varations are supported.

New custom properties

--spectrum-contextual-help-body-color
--spectrum-contextual-help-body-line-height
--spectrum-contextual-help-body-sans-serif-font-family
--spectrum-contextual-help-body-sans-serif-font-style
--spectrum-contextual-help-body-sans-serif-font-weight
--spectrum-contextual-help-title-color
--spectrum-contextual-help-title-font-style
--spectrum-contextual-help-title-font-weight
--spectrum-contextual-help-title-line-height
--spectrum-contextual-help-title-sans-serif-font-family

New mods

--mod-contextual-help-body-line-height
--mod-contextual-help-body-sans-serif-font-family
--mod-contextual-help-body-sans-serif-font-style
--mod-contextual-help-body-sans-serif-font-weight
--mod-contextual-help-body-size
--mod-contextual-help-title-color
--mod-contextual-help-title-font-style
--mod-contextual-help-title-font-weight
--mod-contextual-help-title-line-height
--mod-contextual-help-title-sans-serif-font-family
--highcontrast-contextual-help-heading-color
--highcontrast-contextual-help-title-color

Removed mods

--highcontrast-contextual-help-heading-color

Screenshots

To-do list

I have read the contribution guidelines.
I have updated relevant storybook stories and templates.
I have tested these changes in Windows High Contrast mode.
If my change impacts other components, I have tested to make sure they don't break.
If my change impacts documentation, I have updated the documentation accordingly.
✨ This pull request is ready to merge. ✨

changeset-bot · 2025-06-06T23:08:06Z

🦋 Changeset detected

Latest commit: 662f926

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@spectrum-css/contextualhelp	Major
@spectrum-css/bundle	Patch
@spectrum-css/preview	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2025-06-06T23:13:35Z

🚀 Deployed on https://pr-3909--spectrum-css.netlify.app

github-actions · 2025-06-06T23:18:27Z

File metrics

Summary

Total size: 1.42 MB^*

Package	Size	Minified	Gzipped
contextualhelp	5.08 KB	4.89 KB	1.11 KB

contextualhelp

Filename	Head	Minified	Gzipped	Compared to base
index.css	5.08 KB	4.89 KB	1.11 KB	🔴 ⬆ 2.87 KB
metadata.json	2.91 KB	-	-	🔴 ⬆ 1.64 KB

* Size is the sum of all main files for packages in the library.
* An ASCII character in UTF-8 is 8 bits or 1 byte.

castastrophe

This looking great. Well documented and thanks for the storybook clean-up. I left one small suggestion about how we document high contrast hooks.

.changeset/legal-lands-warn.md

components/contextualhelp/index.css

marissahuysentruyt

Some questions for you!

Is there a reason we have customStyles on every story? Can we get rid of any and use our CSS instead? I haven't actually tried removing them, so we might, I'm not sure.
I couldn't comment on the action button code, but I think we need to gather the globals data so that we can appropriately render both the small action button for large/mobile, and the XS action button for medium/desktop

// before the return statement
const { globals = {} } = context;
const scale = globals.scale ?? "medium"; // this const may not be necessary, so you could refactor this out if you wanted

// then in the ActionButton call, change the size declaration: 
size: scale === "medium" ? "xs" : "s",

Could you double check all of the mods in the CSS? There were quite a few places where I was seeing --mod-spectrum-contextual-help* instead of just --mod-contextual-help*. (places where it was already like that, I mean)
How does contextual help get triggered? Would we want to add isSelected: false to the action button at all, just to match the design, or is this component triggered because an action button was selected?

marissahuysentruyt · 2025-06-17T19:09:28Z

components/contextualhelp/stories/contextualhelp.stories.js

@@ -180,74 +190,14 @@ TopPopover.storyName = "Default - top popover";
 export const HelpDefault = Template.bind({});


Since we removed the other help icon stories, what do you think about just adding some extra documentation here about them?

"All variants and positions of the contextual help component can be configured with a help icon. When display help or resources to learn more..." and so on.

Added:

All variants and positions of the contextual help component can be configured with a help icon.

I think that's clear enough inasmuch as it clarifies how it's used and what sets it apart from other use cases. We can add more, but the icon alone distinguishing it makes me hesitant to do so. ✨

.changeset/legal-lands-warn.md

components/contextualhelp/index.css

marissahuysentruyt · 2025-06-17T19:43:28Z

components/contextualhelp/index.css

+	--spectrum-contextual-help-body-line-height: var(--spectrum-line-height-200);
+
+	--spectrum-contextual-help-body-color: var(--spectrum-body-color);
+}


Do we want to set the --mod-popover-corner-radius passthrough at all? That would mean the mod and the --spectrum custom props are the same value, but if they ever change to be different, it could be nice to already have that passthrough set up for contextual help.

I also think we've gotten feedback that we need to be more explicit with the cascades, so in my head, that means setting the mod passthroughs even if they're the same value for now. Thoughts?

I have the same question for --mod-popover-animation-distance. That mod for the distance between the popover and its source specifically gave us some trouble in picker initially, so my gut says just define it for contextual help (even though again, I think it's technically the same as the --spectrum variable)

That makes sense to me — we set --mod-popover-corner-radius in the coach mark migration and that leveraged the popover extensively. I went ahead and dropped a passthrough section in here as well. ✨

Took one more look at this and could definitely use some eyes on it to see if I threaded it through everything properly. 😅

components/contextualhelp/index.css

.changeset/legal-lands-warn.md

components/contextualhelp/stories/contextualhelp.stories.js

cdransf self-assigned this Jun 6, 2025

cdransf added size-5 L ~30-42hrs; lots of effort or complexity, most of a sprint needed to complete. wip This is a work in progress, don't judge. skip_vrt Add to a PR to skip running VRT (but still pass the action) labels Jun 6, 2025

cdransf force-pushed the cdransf/s2-migration-contextual-help branch from 3bdff09 to 1850227 Compare June 9, 2025 20:11

cdransf changed the title ~~WIP(contextual-help): S2 migration~~ feat(contextual-help): S2 migration Jun 9, 2025

cdransf force-pushed the cdransf/s2-migration-contextual-help branch from de08037 to 57323f8 Compare June 9, 2025 23:00

cdransf marked this pull request as ready for review June 10, 2025 19:38

cdransf force-pushed the cdransf/s2-migration-contextual-help branch from c56c432 to f237622 Compare June 10, 2025 19:39

cdransf requested review from castastrophe, rise-erpelding, marissahuysentruyt and aramos-adobe June 10, 2025 19:39

cdransf added ready-for-review and removed wip This is a work in progress, don't judge. labels Jun 10, 2025

cdransf force-pushed the cdransf/s2-migration-contextual-help branch from f237622 to 40e2b6b Compare June 10, 2025 21:40

castastrophe approved these changes Jun 11, 2025

View reviewed changes

.changeset/legal-lands-warn.md Outdated Show resolved Hide resolved

components/contextualhelp/index.css Show resolved Hide resolved

cdransf force-pushed the cdransf/s2-migration-contextual-help branch 2 times, most recently from 1bceda1 to 75a08f1 Compare June 12, 2025 17:33

marissahuysentruyt requested changes Jun 17, 2025

View reviewed changes

marissahuysentruyt reviewed Jun 17, 2025

View reviewed changes

components/contextualhelp/stories/contextualhelp.stories.js Show resolved Hide resolved

cdransf force-pushed the cdransf/s2-migration-contextual-help branch 4 times, most recently from aca04a3 to cb8314b Compare June 17, 2025 22:39

cdransf added 2 commits June 17, 2025 15:45

feat(contextual-help): S2 migration

89da5cb

fix(contextual-help): simplify link storybook controls

74f9813

cdransf added 6 commits June 17, 2025 15:45

fix(contextual-help): remove duplicative stories from docs

f1e177e

fix(contextual-help): remove WHC property from changelog mods section

3dad274

fix(contextual-help): mod names + min inline size property

ae3ff27

fix(contextual-help): fix changeset typo + update formatting

bfbeda0

fix(contextual-help): abstract out direct token references

5902b16

fix(contextual-help): update metadata

ef4e9c5

cdransf force-pushed the cdransf/s2-migration-contextual-help branch from cb8314b to ef4e9c5 Compare June 17, 2025 22:45

fix(contextual-help): update stories + tests

662f926

cdransf force-pushed the cdransf/s2-migration-contextual-help branch from 6bff760 to 662f926 Compare June 18, 2025 00:00

		@@ -180,74 +190,14 @@ TopPopover.storyName = "Default - top popover";
		export const HelpDefault = Template.bind({});

feat(contextual-help): S2 migration #3909

Are you sure you want to change the base?

feat(contextual-help): S2 migration #3909

Conversation

cdransf commented Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

S2 migration for contextual help

New custom properties

New mods

Removed mods

Screenshots

To-do list

Uh oh!

changeset-bot bot commented Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

File metrics

Summary

contextualhelp

Uh oh!

castastrophe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

marissahuysentruyt left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

cdransf Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marissahuysentruyt Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

cdransf Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

cdransf Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cdransf commented Jun 6, 2025 •

edited

Loading

changeset-bot bot commented Jun 6, 2025 •

edited

Loading

github-actions bot commented Jun 6, 2025 •

edited

Loading

github-actions bot commented Jun 6, 2025 •

edited

Loading

marissahuysentruyt left a comment •

edited

Loading

cdransf Jun 17, 2025 •

edited

Loading